I am not sure about this. On one hand this makes the overlay self-contained. On the other, it is no longer pure – and if the overlay no longer works with a single coherent set of packages, there are not many reasons to choose it over just legacyPackages.

I guess I'm not very familiar with both creating and using overlays; I use them very coarsely in my dotfiles when I use them at all. Since the package requires napalm to build, providing it purely would require adding the napalm overlay to prev, right? Is something like this possible?

let
  pkg = import prev {
    overlays = [ napalm.overlay ];
  };
in
  {
    hello-world = pkg.buildPackage ./hello-world { };
  };

nix flake check doesn't seem to error on it, so I'll test it out

The answer is no, it does not.

That would re-create a new Nixpkgs instance from scratch, likely discarding other overlays in the stack.

You could do something like the following:

final: prev:
let
ourOverlay = final: prev:
  {
    hello-world = prev.napalm.buildPackage ./hello-world { };
  };
in
prev.lib.composeExtensions napalm.overlay ourOverlay

but that would also override napalm people put in their overlays.

Or maybe something like:

final: prev:
let
  pkgsWithNapalm = napalm.overlay final prev;
in
  {
    hello-world = pkgsWithNapalm.napalm.buildPackage ./hello-world { };
  };

But that would still not allow people to override napalm.

We could allow that using conditional stacking:

final: prev:
let
  pkgsWithNapalm = if prev ? napalm then prev else napalm.overlay final prev;
in
  {
    hello-world = pkgsWithNapalm.napalm.buildPackage ./hello-world { };
  };

But I think that is too magic and would just befuddle people.

So I tend to use just plain old

final: prev:
  {
    hello-world = prev.napalm.buildPackage ./hello-world { };
  };

And mention the dependency in readme.

But maybe there is some other idiom concerning interdependent overlays that I am not aware of. Maybe ask on Discourse or Matrix?

I like the conditional stacking, but yeah, might be complex to have in a template. Not sure that it's common though to have an external builder be passed purely though

Alright, I added an implementation of the conditional stacking I've managed to get working right, alongside some explanatory comments. It's close to what you had, but with napalm.buildPackage as the checked attr, as that's both specifically what we need, and should help avoid collision problems (e.g. there's already a napalm package in nixpkgs, but it's different).

It's probably enough to do things like this, as overlays themselves are more of an advanced use-case.

EDIT: Got it working in 7bfe032 specifically.